home *** CD-ROM | disk | FTP | other *** search
Wrap
head 1.2; branch ; access ; symbols ; locks ; strict; comment @@; 1.2 date 92.03.29.12.13.19; author death; state Exp; branches ; next 1.1; 1.1 date 92.03.22.15.48.36; author death; state Exp; branches ; next ; desc @This is the description of the Reply object. Read it. @ 1.2 log @ turns out that 2.0 wants init calls to be in the object, not the class. Modified doc to reflect changed in the code. @ text @{\rtf0\ansi{\fonttbl\f0\fnil Palatino-Roman;\f1\ftech Symbol;\f2\fnil NewCenturySchlbk-Roman;} \paperw14520 \paperh13540 \margl120 \margr0 {\colortbl\red0\green0\blue0;} \pard\tx5700\tx11360\f0\b0\i0\ul0\fs24 $Revision: 1.1 $ $Author: death $ $Date: 92/03/22 15:48:36 $\ \pard \ \pard\tx3120\tx3620\tx4120\fs16\li2620 \ \fs28 \ \fs16 \ \fs28 \ \fs16 \ \pard\b\li1100 \ \ \ \ \fs36 Reply\ \fs16 \ \pard\tx7140\b0\fs28\li2100 INHERITS FROM ErrorInfo\ \fs16 \ \fs28 DECLARED IN Reply.h\ \fs16 \ \ \ \fs28 CLASS DESCRIPTION\ \fs16 \ \pard\tx3120\tx3620\tx4120\fs28\li2620 Reply is a subclass of the ErrorInfo class. Like it's parent class, Reply is designed to mainly be used as a return value from methods. Unlike it's parent, it does not confine itself to merely holding status information. Instead, it serves the dual purpose of returning status codes and messages, along with returning result values.\ \fs16 \ \fs28 Put another way, an obvious problem with the ErrorInfo class is that it sometimes becomes awkward when one wants to return an error status as well as potentially returning data. The Reply class provides both services in one object.\ \fs16 \ \fs28 A Reply object contains the same error information that an ErrorInfo ones does. It also, however, can contain one data value that is being returned.\ \fs16 \ \fs28 The Reply class understands a certain set of data types. One must subclass it to get more specialized types. The data types it understands are:\ char\ byte \ signed and unsigned short int\ signed and unsigned int\ signed and unsigned long int\ Cstring\ id\ When one creates a Reply object, one assigns it a value, specifying the data type. In all cases save the last, when this is assigned, a copy is made of the data. The receiver of the reply can then retrieve the data using an appropriate method, and free the Reply object.\ The data will be copied again for the user, so that when the Reply is freed, it can dispose of the data it holds appropriately. Note that it will \i not \i0 send a free message to the returned object.\ \fs16 \ \fs28 One can also pass `general' information with the Reply object. This is a four byte quantity which is not altered in any way by the Reply object, nor freed when it is destroyed itself. Thus, one can pass arbitrary pointers in this way within a thread. \ \fs16 \ \fs28 Using the class is much like using the ErrorInfo class, save that there are more initialization parameters.\ \fs16 \ \pard\tx7140\li2100 \ \ \fs28 INSTANCE VARIABLES\ \fs16 \ \pard\tx6640\tx9660\tx10180\i\fs28\fi-4040\li6640 Inherited from Object \i0 Class isa;\ \fs16 \ \i\fs28 Inherited from ErrorInfo \i0 long int errorKind;\ Cstring errorText; \pard\tx9660\tx10180\fi-520\li7140 \ long int errorCode;\ \pard\tx7140\tx10180\tx10680\fs16\fi-4540\li7140 \ \pard\tx6640\tx9660\tx10180\i\fs28\fi-4040\li6640 Declared in Reply \i0 long int \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\fc0 theType \pard\tx6640\tx9660\tx10180\fi-4040\li6640 ;\ long int theData; \pard\tx9660\tx10180\fi-520\li7140 \ \pard\tx7140\tx10180\tx10680\fs16\fi-4540\li7140 \ \fs28 dataType A flag indicating what kind of data is present\ \fs16 \ \fs28 theData storage place for data being returned\ \pard\tx7140\fs16\li2100 \ \ \ \fs28 METHOD TYPES\ \fs16 \ \pard\tx7140\tx10180\tx10680\fs28\fi-4540\li7140 Creating/Initializing, and Freeing \f1 - \f0 initReplyWithCode:Text:Kind:Data:Type:\ \pard\tx10180\tx10680\f1\fi-520\li7660 - \f0 initReplyWithCode:Text:Data:Type:\ \f1 - \f0 initReplyWithCode:Text:Data:\ \f1 - \f0 free\ \pard\tx7140\tx10180\tx10680\fs16\fi-4540\li7140 \ \fs28 Accessing stored data \f1 - \f0 getByte \ \pard\tx10180\tx10680\f1\fi-520\li7660 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getChar \pard\tx10180\tx10680\fi-520\li7660 \ \f1 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getCstring \pard\tx10180\tx10680\fi-520\li7660 \ \f1 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getGeneral \pard\tx10180\tx10680\fi-520\li7660 \ \f1 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getShort \pard\tx10180\tx10680\fi-520\li7660 \ \f1 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getInt \pard\tx10180\tx10680\fi-520\li7660 \ \f1 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getLong \pard\tx10180\tx10680\fi-520\li7660 \ \f1 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getObject \pard\tx10180\tx10680\fi-520\li7660 \ \f1 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getUnsignedShort \pard\tx10180\tx10680\fi-520\li7660 \ \f1 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getUnsignedInt \pard\tx10180\tx10680\fi-520\li7660 \ \f1 - \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\f0\fc0 getUnsignedLong \pard\tx10180\tx10680\fi-520\li7660 \ \pard\tx7140\fs16\li2100 \ \ \ \fs28 CLASS METHODS\ \fs16 \ \b \ \b0\fs28 None\ \fs16 \ \ \ \fs28 INSTANCE METHODS\ \fs16 \ \b \ \fs28 initReplyWithCode:Text:Kind:Data:Type:\ \pard\tx3260\b0\fi-1020\li3620 + (id) \b initReplyWithCode: \b0 (long int) \i code \b\i0 Text: \b0 (Cstring) \i text \b\i0 Kind: \b0 (long int) \i kind\ \b\i0 Data: \b0 (void*) \i dataVal \i0 \b Type: \b0 (int) \i dataType \b\i0 \ \pard\fs16\fi-1020\li3620 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Creates a new reply object with a full set of values for error code, text and kind, the data to be returned, and the kind of data. Data type codes are listed below.\ \pard\tx7140\fs16\li2100 \ \b \ \fs28 initReplyWithCode:Text:Data:Type:\ \pard\b0\fi-1020\li3620 + (id) \b \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\fc0 initReplyWithCode \pard\fi-1020\li3620 : \b0 (long int) \i code \b\i0 Text: \b0 (Cstring) \i text \b\i0 Data: \b0 (void*) \i dataVal \i0 \ \pard\tx3260\b\fi-1020\li3620 Type: \b0 (int) \i dataType \b\i0 \ \pard\fs16\fi-1020\li3620 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Calls \b initReplyWithCode:Text:Kind:Data:Type: \b0 using errKindGeneral for the \i kind \i0 parameter. This, then, simply serves as a more common case wrapper around the preceeding method.\ \pard\tx7140\fs16\li2100 \ \b \ \fs28 initReplyWithCode:Text:Data:\ \pard\b0\fi-1020\li3620 + (id) \b \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\fc0 initReplyWithCode \pard\fi-1020\li3620 : \b0 (long int) \i code \b\i0 Text: \b0 (Cstring) \i text \b\i0 Data: \b0 (void*) \i dataVal \pard\tx3260\b\i0\fi-1020\li3620 \ \pard\fs16\fi-1020\li3620 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Calls \b initReplyWithCode:Text:Kind:Data: \b0 using errKindGeneral for the \i kind \i0 parameter and typeGENERAL for the \i dataType \i0 parameter.\ \pard\tx7140\fs16\li2100 \ \b \ \fs28 free\ \pard\b0\fi-1020\li3620 + \b free\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Disposes of the instance values of the method and frees the object..\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getByte\ \pard\f1\b0\fi-1020\li3620 - \f0 (byte) \b getByte\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Reply's data interpreted as if it were a byte.\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getChar\ \pard\f1\b0\fi-1020\li3620 - \f0 (char) \b getChar\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Reply's data interpreted as if it were a character.\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getCstring\ \pard\f1\b0\fi-1020\li3620 - \f0 (Cstring) \b getCstring\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the data as if it were a Cstring. If it is not, this will not warn you in any way.\ \pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\b\fc0 \ \pard\tx7140\li2100 getGeneral\ \pard\f1\b0\fi-1020\li3620 - \f0 (void*) \b getGeneral\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns the data stored in the object in the most general form possible.\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getShort\ \pard\f1\b0\fi-1020\li3620 - \f0 (byte) \b getShort\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Reply's data interpreted as if it were a short.\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getInt\ \pard\f1\b0\fi-1020\li3620 - \f0 (int) \b getInt\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Reply's data interpreted as if it were an int.\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getLong\ \pard\f1\b0\fi-1020\li3620 - \f0 (long int) \b getLong\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Reply's data interpreted as if it were a long int.\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getObject\ \pard\f1\b0\fi-1020\li3620 - \f0 (id) \b getObject\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns the object that the Reply object is returning.\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getUnsignedShort\ \pard\f1\b0\fi-1020\li3620 - \f0 (unsigned short) \b getUnsignedShort\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Reply's data interpreted as if it were an unsigned short.\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getUnsignedInt\ \pard\f1\b0\fi-1020\li3620 - \f0 ( \pard\tx960\tx1920\tx2880\tx3840\tx4800\tx5760\tx6720\tx7680\tx8640\tx9600\fi-1020\li3620 unsigned \pard\fi-1020\li3620 int) \b getUnsignedInt\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Reply's data interpreted as if it were an unsigned int.\ \fs16 \ \pard\tx7140\b\li2100 \ \fs28 getUnsignedLong\ \pard\f1\b0\fi-1020\li3620 - \f0 ( \pard\tx960\tx1920\tx2880\tx3840\tx4800\tx5760\tx6720\tx7680\tx8640\tx9600\fi-1020\li3620 unsigned \pard\fi-1020\li3620 long int) \b getUnsignedLong\ \fs16 \ \pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Reply's data interpreted as if it were an unsigned long int.\ \fs16 \ \pard\tx7140\li2100 \ \ \fs28 BUGS AND PROBLEMS\ \fs16 \ \pard\tx3120\tx3620\tx4120\fs28\li2620 Dealing with data types is a bit cumbersome? \ Probably we should override the error init methods some so if someone calls them, they don't get gibberish?\ I doubt I've tested passing signed data enough...\ \fs16 \ \pard\tx7140\li2100 \ \ \fs28 ENHANCEMENT IDEAS\ \fs16 \ \pard\tx3120\tx3620\tx4120\fs28\li2620 Fix the above, and deal with more arbitrary data.\ Add support for things like my theoretical string object, where you do want to free the object.\ \b\i Is \b0\i0 there a way to deal with returning different data types from one function?\ \fs16 \ \pard\tx7140\li2100 \ \ \fs28 CONSTANTS AND DEFINED TYPES\ \fs16 \ \pard\tx6480\tx7180\fs24\li2620 #define TYPE_NONE 0\ #define TYPE_GENERAL 1\ #define TYPE_CSTRING 2\ #define TYPE_BYTE 3\ #define TYPE_CHAR 4\ #define TYPE_SHORT 5\ #define TYPE_INT 6\ #define TYPE_LONG 7\ #define TYPE_USHORT 8\ #define TYPE_UINT 9\ #define TYPE_ULONG 10\ #define TYPE_OBJECT 11\ \pard\tx3120\tx3620\tx4120\fs16\li2620 \ \pard\tx7140\li2100 \ \ \fs28 METHODS AND CONSTANTS FROM SUPERCLASSES\ \pard\tx7140\tx10180\tx10680\fs16\fi-4540\li7140 \ \fs28 Creating/Initializing, and Freeing \f1 + \f0 newErrorWithCode:Text:Kind:\ \pard\tx10180\tx10680\f1\fi-520\li7660 + \f0 newErrorWithCode:Text:\ + free\ \pard\tx7140\fs16\li2100 \ \pard\tx7140\tx10180\tx10680\fs28\fi-4540\li7140 Accessing error values \f1 - \f0 getErrorKind \ \pard\tx10180\tx10680\f1\fi-520\li7660 - \f0 getErrorText \ \f1 - \f0 getErrorCode\ \pard\tx7140\fs16\li2100 \ \pard\tx6480\tx7180\fs24\li2620 #define ERRKIND_NONE 0\ #define ERRKIND_GENERAL 1\ #define ERRKIND_USER 2\ #define ERRKIND_OS 3\ \pard\tx3120\tx3620\tx4120\fs16\li2620 \ \pard\tx7140\li2100 \ \ \fs28 MODIFICATION HISTORY\ \fs16 \ \pard\tx3120\tx3620\tx4120\fs28\li2620 $Log: Reply.rtf,v $Revision 1.1 92/03/22 15:48:36 deathInitial revision \fi-20\li3120 \ } @ 1.1 log @Initial revision @ text @d3 1 a3 1 \paperh14260 d7 1 a7 1 \pard\tx5700\tx11360\f0\b0\i0\ul0\fs24 $Revision: 1.2 $ $Author: death $ $Date: 92/02/09 18:43:55 $\ d101 1 a101 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\fc0 theType d123 2 a124 3 \f1 + \f0 initReplyWithCode :Text:Kind:Data:Type:\ d126 1 a126 1 \pard\tx10180\tx10680\f1\fi-520\li7660 + d129 1 a129 1 \f1 + d132 1 a132 1 \f1 + d142 1 a142 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getChar d146 1 a146 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getCstring d150 1 a150 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getGeneral d154 1 a154 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getShort d158 1 a158 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getInt d162 1 a162 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getLong d166 1 a166 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getObject d170 1 a170 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getUnsignedShort d174 1 a174 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getUnsignedInt d178 1 a178 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\f0\fc0 getUnsignedLong d191 12 d237 1 a237 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\fc0 initReplyWithCode d270 1 a270 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\fc0 initReplyWithCode a306 7 \pard\tx7140\li2100 \ \ \fs28 INSTANCE METHODS\ \pard\tx3120\tx3620\tx4120\fs16\li2620 \ d347 1 a347 1 \pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\b\fc0 \ d556 1 a556 1 \pard\tx3120\tx3620\tx4120\fs28\li2620 $Log: $ @